<?php

/**
 * Library :: DAL (Data Access Layer) :: DataObject
 *
 * Warlock is free software. This version may have been modified pursuant
 * to the GNU General Public License, and as distributed it includes or
 * is derivative of works licensed under the GNU General Public License or
 * other free or open source software licenses.
 *
 * @package    warlock
 * @author     David Cole <neophyte@sourcetutor.com>
 * @license    GNU/GPL v2
 */


class DAL_DataObject extends Object
{
    /**
     * Table Name
     *
     * The table to which this Data Object relates
     *
     * @var DAL
     * @access public
     */
    var $Table;

    /**
     * Field Definitions
     *
     * An associative array holding field => array() pairs for
     * each of the fields in the array.
     *
     * Listed below are all the possible attribute => value pairs
     * of the field array.
     *
     * 'type'
     *   - STRING     Covers CHAR, VARCHAR, TINYTEXT, TEXT, MEDIUMTEXT and LONGTEXT
     *   - INTEGER    Covers TINYINT, SMALLINT, MEDIUMINT, INT and BIGINT
     *   - NUMERIC    Covers DECIMAL and YEAR
     *   - FLOAT      Covers FLOAT and DOUBLE
     *   - DATE       Covers DATE
     *   - TIME       Covers TIME
     *   - DATETIME   Covers DATETIME
     *   - TIMESTAMP  Covers TIMESTAMP
     *   - BOOLEAN    Covers BOOLEAN, CHAR(1) and TINYINT(1)
     *
     * 'size'           - int,    Maximum size of the field
     * 'scale'          - int,    Digits that can be stored following the decimal point
     * 'autoincrement ' - bool,   On an INSERT the database will generate a unique value (unless a non-null value is supplied manually)
     * 'unsigned'       - bool,   Marks the field as being unsigned
     * 'null'           - bool,   If the field should allow null values
     * 'default'        - string, Default value to be used during an INSERT
     * 'autoinsert'     - bool,   A value will automatically be inserted according to the field's TYPE
     *                                - DATETIME  Current date and time will be inserted
     *                                - DATE      Current date will be inserted
     * 'autoupdate'     - bool,   Same as autoinsert but for updates
     * 'true'           - char,   For BOOLEAN fields this identifies how a TRUE value will be recorded in the database. It may be '1' or 'T' or 'Y'
     * 'false'          - char,   For BOOLEAN fields this identifies how a FALSE value will be recorded in the database. It may be '0' or 'F' or 'N'
     *
     * @var array
     * @access public
     */
    var $Fields = array();

    /**
     * Relationships
     *
     * An indexed array of all the child relationships this
     * table depends upon.
     *
     * Detailed below are the attribute => value pairs which
     * can be used when forming a relationship.
     *
     * 'table'       - string,  Name of the child table
     * 'do'          - string,  Name of the Data Object associated with the table
     * 'alias'       - string,  Child alias in cases of multiple relations using the same table
     * 'fields'      - array,   Associative array of child_field => child_field_alias of the fields to make readable
     * 'type'
     *   - RESTRICTED   Do not allow the parent to be deleted if any associated records on this child table exist
     *   - CASCADE      When the parent is deleted then also delete all associated records on this child table
     *   - NULLIFY      When the parent is deleted then update all associated records on this child table by setting the foreign key field(s) to NULL
     * 'relate'      - array, Associate array of parent_field => child_field pairs.
     *
     * @var array
     * @access public
     */
    var $Relationships = array();

    /**
     * Interests
     *
     * This array allows this data object to be informed when records are deleted
     * from the data objects in the given indexed array.
     *
     * @var array
     * @access public
     */
    var $Interests = array();


    /**
     * Primary Key
     *
     * An indexed array of the fields within
     * the table which make up the primary key.
     *
     * @var array
     * @access public
     */
    var $PrimaryKey;

    /**
     * Data Access Layer
     *
     * @var DAL
     * @access private
     */
    var $_DAL;

    /**
     * Data Object Name
     *
     * @var DAL
     * @access private
     */
    var $_Name;

    /**
     * Constructor
     *
     * @return DAL_DataObject
     */
    function __construct()
    {
        $this->_DAL  = &Vault::Get('DAL');
        $this->_Name = str_replace('dal_dataobject_', '', get_class($this));
    }

    /**
     * Select
     *
     * Default implementation of the Select method for
     * Data Objects.
     *
     * @abstract
     */
    function Select($where = array(), $order = array(), $rows = false, $offset = false, $mode = 'ASSOC')
    {
        return $this->_DAL->DAO->Select($this->_Name, $where, $order, $rows, $offset, $mode);
    }

    /**
     * Insert
     *
     * Default implementation of the Insert method for
     * Data Objects.
     *
     * @abstract
     */
    function Insert($data = array())
    {
        return $this->_DAL->DAO->Insert($this->_Name, $data);
    }

    /**
     * Update
     *
     * Default implementation of the Update method for
     * Data Objects.
     *
     * @abstract
     */
    function Update($data = array(), $where = array())
    {
        return $this->_DAL->DAO->Update($this->_Name, $data, $where);
    }

    /**
     * Delete
     *
     * Default implementation of the Delete method for
     * Data Objects.
     *
     * @abstract
     */
    function Delete($where = array())
    {
        return $this->_DAL->DAO->Delete($this->_Name, $where);
    }

    /**
     * Interests
     *
     * If any records are deleted from a Data Object of interest to us {@link $this->Interests}
     * then this method is called.
     *
     * This function MUST be implemented in the Data Object if Data Objects are added
     * to the Interests array.
     *
     * @param  string  $do    Name of the Data Object records have been deleted from
     * @param  array   $keys  Primary Keys which where deleted from the Data Object
     *
     * @return void
     * @access public
     */
    function Interests($do, $keys)
    {
        return;
    }
}

?>